home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / glibmm-2.4 / glibmm / iochannel.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-04-20  |  25.6 KB  |  696 lines
  1. // -*- c++ -*-
  2. // Generated by gtkmmproc -- DO NOT MODIFY!
  3. #ifndef _GLIBMM_IOCHANNEL_H
  4. #define _GLIBMM_IOCHANNEL_H
  5.  
  6.  
  7. // -*- c++ -*-
  8. /* $Id: iochannel.hg,v 1.7 2005/01/21 12:48:05 murrayc Exp $ */
  9.  
  10. /* Copyright (C) 2002 The gtkmm Development Team
  11.  *
  12.  * This library is free software; you can redistribute it and/or
  13.  * modify it under the terms of the GNU Library General Public
  14.  * License as published by the Free Software Foundation; either
  15.  * version 2 of the License, or (at your option) any later version.
  16.  *
  17.  * This library is distributed in the hope that it will be useful,
  18.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20.  * Library General Public License for more details.
  21.  *
  22.  * You should have received a copy of the GNU Library General Public
  23.  * License along with this library; if not, write to the Free
  24.  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25.  */
  26.  
  27.  
  28. #include <glibmm/error.h>
  29. #include <glibmm/main.h>
  30. #include <glibmm/refptr.h>
  31. #include <glibmm/ustring.h>
  32. #include <glib/gtypes.h>
  33.  
  34. #include <string>
  35. #include <glibmmconfig.h>
  36.  
  37. GLIBMM_USING_STD(string)
  38.  
  39. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  40. extern "C" { typedef struct _GIOChannel GIOChannel; }
  41. #endif
  42.  
  43.  
  44. namespace Glib
  45. {
  46.  
  47. class Source;
  48. class IOSource;
  49.  
  50. /** @addtogroup glibmmEnums Enums and Flags */
  51.  
  52. /**
  53.  * @ingroup glibmmEnums
  54.  */
  55. enum SeekType
  56. {
  57.   SEEK_TYPE_CUR,
  58.   SEEK_TYPE_SET,
  59.   SEEK_TYPE_END
  60. };
  61.  
  62.  
  63. /**
  64.  * @ingroup glibmmEnums
  65.  */
  66. enum IOStatus
  67. {
  68.   IO_STATUS_ERROR,
  69.   IO_STATUS_NORMAL,
  70.   IO_STATUS_EOF,
  71.   IO_STATUS_AGAIN
  72. };
  73.  
  74.  
  75. /**
  76.  * @ingroup glibmmEnums
  77.  * @par Bitwise operators:
  78.  * <tt>%IOFlags operator|(IOFlags, IOFlags)</tt><br>
  79.  * <tt>%IOFlags operator&(IOFlags, IOFlags)</tt><br>
  80.  * <tt>%IOFlags operator^(IOFlags, IOFlags)</tt><br>
  81.  * <tt>%IOFlags operator~(IOFlags)</tt><br>
  82.  * <tt>%IOFlags& operator|=(IOFlags&, IOFlags)</tt><br>
  83.  * <tt>%IOFlags& operator&=(IOFlags&, IOFlags)</tt><br>
  84.  * <tt>%IOFlags& operator^=(IOFlags&, IOFlags)</tt><br>
  85.  */
  86. enum IOFlags
  87. {
  88.   IO_FLAG_APPEND = 1 << 0,
  89.   IO_FLAG_NONBLOCK = 1 << 1,
  90.   IO_FLAG_IS_READABLE = 1 << 2,
  91.   IO_FLAG_IS_WRITEABLE = 1 << 3,
  92.   IO_FLAG_IS_SEEKABLE = 1 << 4,
  93.   IO_FLAG_GET_MASK = 0x0,
  94.   IO_FLAG_SET_MASK = 0x1
  95. };
  96.  
  97. /** @ingroup glibmmEnums */
  98. inline IOFlags operator|(IOFlags lhs, IOFlags rhs)
  99.   { return static_cast<IOFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
  100.  
  101. /** @ingroup glibmmEnums */
  102. inline IOFlags operator&(IOFlags lhs, IOFlags rhs)
  103.   { return static_cast<IOFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
  104.  
  105. /** @ingroup glibmmEnums */
  106. inline IOFlags operator^(IOFlags lhs, IOFlags rhs)
  107.   { return static_cast<IOFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
  108.  
  109. /** @ingroup glibmmEnums */
  110. inline IOFlags operator~(IOFlags flags)
  111.   { return static_cast<IOFlags>(~static_cast<unsigned>(flags)); }
  112.  
  113. /** @ingroup glibmmEnums */
  114. inline IOFlags& operator|=(IOFlags& lhs, IOFlags rhs)
  115.   { return (lhs = static_cast<IOFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
  116.  
  117. /** @ingroup glibmmEnums */
  118. inline IOFlags& operator&=(IOFlags& lhs, IOFlags rhs)
  119.   { return (lhs = static_cast<IOFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
  120.  
  121. /** @ingroup glibmmEnums */
  122. inline IOFlags& operator^=(IOFlags& lhs, IOFlags rhs)
  123.   { return (lhs = static_cast<IOFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
  124.  
  125.  
  126. /** Exception class for IOChannel errors.
  127.  */
  128. class IOChannelError : public Glib::Error
  129. {
  130. public:
  131.   enum Code
  132.   {
  133.     FILE_TOO_BIG,
  134.     INVALID_ARGUMENT,
  135.     IO_ERROR,
  136.     IS_DIRECTORY,
  137.     NO_SPACE_LEFT,
  138.     NO_SUCH_DEVICE,
  139.     OVERFLOWN,
  140.     BROKEN_PIPE,
  141.     FAILED
  142.   };
  143.  
  144.   IOChannelError(Code error_code, const Glib::ustring& error_message);
  145.   explicit IOChannelError(GError* gobject);
  146.   Code code() const;
  147.  
  148. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  149. private:
  150.   static void throw_func(GError* gobject);
  151.   friend void wrap_init(); // uses throw_func()
  152. #endif
  153. };
  154.  
  155.  
  156. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  157. class GlibmmIOChannel;
  158. #endif
  159.  
  160. /** IOChannel aims to provide portable I/O support for files, pipes
  161.  * and sockets, and to integrate them with the GLib main event loop.
  162.  *
  163.  * Note that IOChannels implement an automatic implicit character set
  164.  * conversion to the data stream, and usually will not pass by default
  165.  * binary data unchanged.  To set the encoding of the channel, use e.g.
  166.  * set_encoding("ISO-8859-15"). To set the channel to no encoding, use
  167.  * set_encoding() without any arguments.
  168.  *
  169.  * You can create an IOChannel with one of the static create methods, or
  170.  * implement one yourself, in which case you have to 1) override all
  171.  * _vfunc() members. 2) set the GIOChannel flags in your constructor.
  172.  *
  173.  * @note This feature of being able to implement a custom Glib::IOChannel is
  174.  * deprecated in glibmm 2.2.  The vfunc interface has not yet stabilized
  175.  * enough to allow that -- the C++ wrapper went in by pure accident.  Besides,
  176.  * it isn't terribly useful either.  Thus please refrain from overriding any
  177.  * IOChannel vfuncs.
  178.  */
  179. class IOChannel : public sigc::trackable
  180. {
  181.   public:
  182. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  183.   typedef IOChannel CppObjectType;
  184.   typedef GIOChannel BaseObjectType;
  185. #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  186.  
  187. private:
  188.  
  189.  
  190. public:
  191.   virtual ~IOChannel();
  192.  
  193.   /** Open a file @a filename as an I/O channel using mode @a mode.
  194.    * This channel will be closed when the last reference to it is dropped,
  195.    * so there is no need to call close() (though doing so will not cause
  196.    * problems, as long as no attempt is made to access the channel after
  197.    * it is closed).
  198.    * @param filename The name of the file to open.
  199.    * @param mode One of <tt>"r"</tt>, <tt>"w"</tt>, <tt>"a"</tt>,
  200.    *  <tt>"r+"</tt>, <tt>"w+"</tt>, <tt>"a+"</tt>. These have the
  201.    *  same meaning as in <tt>fopen()</tt>.
  202.    * @return An IOChannel for the opened file.
  203.    * @throw Glib::FileError
  204.    */
  205.   static Glib::RefPtr<IOChannel> create_from_file(const std::string& filename, const std::string& mode);
  206.   
  207.  
  208.   /** Creates an I/O channel from a file descriptor.
  209.    * On Unix, IOChannels created with this function work for any file
  210.    * descriptor or socket.
  211.    *
  212.    * On Win32, this can be used either for files opened with the MSVCRT (the
  213.    * Microsoft run-time C library) <tt>_open()</tt> or <tt>_pipe()</tt>,
  214.    * including file descriptors 0, 1 and 2 (corresponding to <tt>stdin</tt>,
  215.    * <tt>stdout</tt> and <tt>stderr</tt>), or for Winsock <tt>SOCKET</tt>s. If
  216.    * the parameter is a legal file descriptor, it is assumed to be such,
  217.    * otherwise it should be a <tt>SOCKET</tt>. This relies on <tt>SOCKET</tt>s
  218.    * and file descriptors not overlapping. If you want to be certain, call
  219.    * either create_from_win32_fd() or create_from_win32_socket() instead as
  220.    * appropriate.
  221.    *
  222.    * The term file descriptor as used in the context of Win32 refers to the
  223.    * emulated Unix-like file descriptors MSVCRT provides. The native
  224.    * corresponding concept is file <tt>HANDLE</tt>. There isn't as of yet
  225.    * a way to get IOChannels for Win32 file <tt>HANDLE</tt>s.
  226.    */
  227.   static Glib::RefPtr<IOChannel> create_from_fd(int fd);
  228.   
  229.  
  230. /* defined(DOXYGEN_SHOULD_SKIP_THIS) actually does the opposite of what it looks like... */
  231. #if defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS)
  232.  
  233.   /** Create an I/O channel for C runtime (emulated Unix-like) file descriptors.
  234.    * After calling add_watch() on a I/O channel returned by this function, you
  235.    * shouldn't call read() on the file descriptor. This is because adding
  236.    * polling for a file descriptor is implemented on Win32 by starting a thread
  237.    * that sits blocked in a <tt>%read()</tt> from the file descriptor most of
  238.    * the time.  All reads from the file descriptor should be done by this
  239.    * internal GLib thread. Your code should call only IOChannel::read().
  240.    */
  241.   static Glib::RefPtr<IOChannel> create_from_win32_fd(int fd);
  242.   
  243.  
  244.   /** Create an I/O channel for a winsock socket. The parameter should be a
  245.    * <tt>SOCKET</tt>. Contrary to I/O channels for file descriptors (on Win32),
  246.    * you can use normal <tt>recv()</tt> or <tt>recvfrom()</tt> on sockets even
  247.    * if GLib is polling them.
  248.    */
  249.   static Glib::RefPtr<IOChannel> create_from_win32_socket(int socket);
  250.   
  251.  
  252. #endif /* defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS) */
  253.  
  254.   /** Read a single UCS-4 character.
  255.    * @retval unichar The Unicode character.
  256.    * @return The status of the operation.
  257.    * @throw Glib::IOChannelError
  258.    * @throw Glib::ConvertError
  259.    */
  260.   
  261.   /** This function cannot be called on a channel with <tt>0</tt> encoding.
  262.    * @param thechar A location to return a character.
  263.    * @param error A location to return an error of type G::ConvertError
  264.    * or G::IOChannelError.
  265.    * @return A G::IOStatus.
  266.    */
  267.   IOStatus read(gunichar& unichar);
  268.  
  269.   /** Read a character sequence into memory.
  270.    * @param buf A buffer to read data into.
  271.    * @param count The size of the buffer in bytes.  Note that the buffer may
  272.    * not be complelely filled even if there is data in the buffer if the
  273.    * remaining data is not a complete character.
  274.    * @retval bytes_read The number of bytes read.  This may be zero even on
  275.    * success if @a count < 6 and the channel's encoding is not <tt>""</tt>.
  276.    * This indicates that the next UTF-8 character is too wide for the buffer.
  277.    * @return The status of the operation.
  278.    * @throw Glib::IOChannelError
  279.    * @throw Glib::ConvertError
  280.    */
  281.   
  282.   /** Replacement for g_io_channel_read() with the new API.
  283.    * @param buf A buffer to read data into.
  284.    * @param count The size of the buffer. Note that the buffer may
  285.    * not be complelely filled even if there is data
  286.    * in the buffer if the remaining data is not a
  287.    * complete character.
  288.    * @param bytes_read The number of bytes read. This may be zero even on
  289.    * success if count < 6 and the channel's encoding is non-<tt>0</tt>.
  290.    * This indicates that the next UTF-8 character is too wide for
  291.    * the buffer.
  292.    * @param error A location to return an error of type G::ConvertError
  293.    * or G::IOChannelError.
  294.    * @return The status of the operation.
  295.    */
  296.   IOStatus read(char* buf, gsize count, gsize& bytes_read);
  297.  
  298.   /** Read a maximum of @a count bytes into @a str.
  299.    * @param count The maximum number of bytes to read.
  300.    * @retval str The characters that have been read.
  301.    * @return The status of the operation.
  302.    * @throw Glib::IOChannelError
  303.    * @throw Glib::ConvertError
  304.    */
  305.   IOStatus read(Glib::ustring& str, gsize count);
  306.  
  307.   /** Read a whole line.
  308.    * Reads until the line separator is found, which is included
  309.    * in the result string.
  310.    * @retval line The line that was read.
  311.    * @return The status of the operation.
  312.    * @throw Glib::IOChannelError
  313.    * @throw Glib::ConvertError
  314.    */
  315.   IOStatus read_line(Glib::ustring& line);
  316.   
  317.  
  318.   /** Reads all the remaining data from the file.
  319.    * @retval str The resulting string.
  320.    * @return Glib::IO_STATUS_NORMAL on success. This function never
  321.    *  returns Glib::IO_STATUS_EOF.
  322.    * @throw Glib::IOChannelError
  323.    * @throw Glib::ConvertError
  324.    */
  325.   IOStatus read_to_end(Glib::ustring& str);
  326.   
  327.  
  328.   /** Write a string to the I/O channel.
  329.    * Note that this method does not return the number of characters written.
  330.    * If the channel is blocking and the returned value is
  331.    * Glib::IO_STATUS_NORMAL, the whole string was written.
  332.    * @param str the string to write.
  333.    * @return The status of the operation.
  334.    * @throw Glib::IOChannelError
  335.    * @throw Glib::ConvertError
  336.    */
  337.   IOStatus write(const Glib::ustring& str);
  338.  
  339.   /** Write a memory area of @a count bytes to the I/O channel.
  340.    * @param buf The start of the memory area.
  341.    * @param count The number of bytes to write.
  342.    * @retval bytes_written The number of bytes written to the channel.
  343.    * @return The status of the operation.
  344.    * @throw Glib::IOChannelError
  345.    * @throw Glib::ConvertError
  346.    */
  347.   
  348.   /** Replacement for g_io_channel_write() with the new API.
  349.    * 
  350.    * On seekable channels with encodings other than <tt>0</tt> or UTF-8, generic
  351.    * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars()
  352.    * may only be made on a channel from which data has been read in the
  353.    * cases described in the documentation for g_io_channel_set_encoding().
  354.    * @param buf A buffer to write data from.
  355.    * @param count The size of the buffer. If -1, the buffer
  356.    * is taken to be a nul-terminated string.
  357.    * @param bytes_written The number of bytes written. This can be nonzero
  358.    * even if the return value is not G::IO_STATUS_NORMAL.
  359.    * If the return value is G::IO_STATUS_NORMAL and the
  360.    * channel is blocking, this will always be equal
  361.    * to @a count  if @a count  >= 0.
  362.    * @param error A location to return an error of type G::ConvertError
  363.    * or G::IOChannelError.
  364.    * @return The status of the operation.
  365.    */
  366.   IOStatus write(const char* buf, gssize count, gsize& bytes_written);
  367.  
  368.   /** Write a single UCS-4 character to the I/O channel.
  369.    * @param unichar The character to write.
  370.    * @return The status of the operation.
  371.    * @throw Glib::IOChannelError
  372.    * @throw Glib::ConvertError
  373.    */
  374.   
  375.   /** This function cannot be called on a channel with <tt>0</tt> encoding.
  376.    * @param thechar A character.
  377.    * @param error A location to return an error of type G::ConvertError
  378.    * or G::IOChannelError.
  379.    * @return A G::IOStatus.
  380.    */
  381.   IOStatus write(gunichar unichar);
  382.  
  383.   /** Seek the I/O channel to a specific position.
  384.    * @param offset The offset in bytes from the position specified by @a type.
  385.    * @param type A SeekType. The type Glib::SEEK_TYPE_CUR is only allowed in
  386.    * those cases where a call to set_encoding() is allowed. See the
  387.    * documentation for set_encoding() for details.
  388.    * @return The status of the operation.
  389.    * @throw Glib::IOChannelError
  390.    * @throw Glib::ConvertError
  391.    */
  392.   
  393.   /** Replacement for g_io_channel_seek() with the new API.
  394.    * @param offset The offset in bytes from the position specified by @a type .
  395.    * @param type A G::SeekType. The type G::SEEK_CUR is only allowed in those
  396.    * cases where a call to g_io_channel_set_encoding()
  397.    * is allowed. See the documentation for
  398.    * g_io_channel_set_encoding() for details.
  399.    * @param error A location to return an error of type G::IOChannelError.
  400.    * @return The status of the operation.
  401.    */
  402.   IOStatus seek(gint64 offset, SeekType type = SEEK_TYPE_SET);
  403.  
  404.   /** Flush the buffers of the I/O channel.
  405.    * @return The status of the operation.
  406.    * @throw Glib::IOChannelError
  407.    * @throw Glib::ConvertError
  408.    */
  409.   
  410.   /** Flushes the write buffer for the GIOChannel.
  411.    * @param error Location to store an error of type G::IOChannelError.
  412.    * @return The status of the operation: One of
  413.    * G::IO_CHANNEL_NORMAL, G::IO_CHANNEL_AGAIN, or
  414.    * G::IO_CHANNEL_ERROR.
  415.    */
  416.   IOStatus flush();
  417.  
  418.   /** Close the I/O channel.
  419.    * Any pending data to be written will be flushed if @a flush is <tt>true</tt>.
  420.    * The channel will not be freed until the last reference is dropped.
  421.    * Accessing the channel after closing it is considered an error.
  422.    * @param flush Whether to flush() pending data before closing the channel.
  423.    * @return The status of the operation.
  424.    * @throw Glib::IOChannelError
  425.    */
  426.   
  427.   /** Close an IO channel. Any pending data to be written will be
  428.    * flushed if @a flush  is <tt>true</tt>. The channel will not be freed until the
  429.    * last reference is dropped using g_io_channel_unref().
  430.    * @param flush If <tt>true</tt>, flush pending.
  431.    * @param err Location to store a G::IOChannelError.
  432.    * @return The status of the operation.
  433.    */
  434.   IOStatus close(bool flush = true);
  435.  
  436.   /** Get the IOChannel internal buffer size.
  437.    * @return The buffer size.
  438.    */
  439.   
  440.   /** Gets the buffer size.
  441.    * @return The size of the buffer.
  442.    */
  443.   gsize get_buffer_size() const;
  444.  
  445.   /** Set the internal IOChannel buffer size.
  446.    * @param size The buffer size the IOChannel should use.
  447.    */
  448.   
  449.   /** Sets the buffer size.
  450.    * @param size The size of the buffer. 0 == pick a good size.
  451.    */
  452.   void set_buffer_size(gsize size);
  453.  
  454.   /** Get the current flags for a IOChannel, including read-only
  455.    * flags such as Glib::IO_FLAG_IS_READABLE.
  456.    *
  457.    * The values of the flags Glib::IO_FLAG_IS_READABLE and
  458.    * Glib::IO_FLAG_IS_WRITEABLE are cached for internal use by the channel when
  459.    * it is created.  If they should change at some later point (e.g. partial
  460.    * shutdown of a socket with the UNIX <tt>shutdown()</tt> function), the user
  461.    * should immediately call get_flags() to update the internal values of these
  462.    * flags.
  463.    * @return Bitwise combination of the flags set on the channel.
  464.    */
  465.   
  466.   /** Gets the current flags for a G::IOChannel, including read-only
  467.    * flags such as G::IO_FLAG_IS_READABLE.
  468.    * 
  469.    * The values of the flags G::IO_FLAG_IS_READABLE and G::IO_FLAG_IS_WRITEABLE
  470.    * are cached for internal use by the channel when it is created.
  471.    * If they should change at some later point (e.g. partial shutdown
  472.    * of a socket with the UNIX shutdown() function), the user
  473.    * should immediately call g_io_channel_get_flags() to update
  474.    * the internal values of these flags.
  475.    * @return The flags which are set on the channel.
  476.    */
  477.   IOFlags get_flags() const;
  478.  
  479.   /** Set flags on the IOChannel.
  480.    * @param flags Bitwise combination of the flags to set.
  481.    * @return The operation result code.
  482.    * @throw Glib::IOChannelError
  483.    */
  484.   
  485.   /** Sets the (writeable) flags in @a channel  to ( @a flags  & G::IO_CHANNEL_SET_MASK).
  486.    * @param flags The flags to set on the IO channel.
  487.    * @param error A location to return an error of type G::IOChannelError.
  488.    * @return The status of the operation.
  489.    */
  490.   IOStatus set_flags(IOFlags flags);
  491.  
  492.   /** Set the buffering status of the I/O channel.
  493.    * The buffering state can only be set if the channel's encoding is
  494.    * <tt>""</tt>. For any other encoding, the channel must be buffered.
  495.    *
  496.    * A buffered channel can only be set unbuffered if the channel's internal
  497.    * buffers have been flushed. Newly created channels or channels which have
  498.    * returned Glib::IO_STATUS_EOF not require such a flush. For write-only
  499.    * channels, a call to flush() is sufficient. For all other channels, the
  500.    * buffers may be flushed by a call to seek().  This includes the possibility
  501.    * of seeking with seek type Glib::SEEK_TYPE_CUR and an offset of zero. Note
  502.    * that this means that socket-based channels cannot be set unbuffered once
  503.    * they have had data read from them.
  504.    *
  505.    * The default state of the channel is buffered.
  506.    *
  507.    * @param buffered Whether to set the channel buffered or unbuffered.
  508.    */
  509.   
  510.   /** The buffering state can only be set if the channel's encoding
  511.    * is <tt>0</tt>. For any other encoding, the channel must be buffered.
  512.    * 
  513.    * A buffered channel can only be set unbuffered if the channel's
  514.    * internal buffers have been flushed. Newly created channels or
  515.    * channels which have returned G::IO_STATUS_EOF
  516.    * not require such a flush. For write-only channels, a call to
  517.    * g_io_channel_flush() is sufficient. For all other channels,
  518.    * the buffers may be flushed by a call to g_io_channel_seek_position().
  519.    * This includes the possibility of seeking with seek type G::SEEK_CUR
  520.    * and an offset of zero. Note that this means that socket-based
  521.    * channels cannot be set unbuffered once they have had data
  522.    * read from them.
  523.    * 
  524.    * On unbuffered channels, it is safe to mix read and write
  525.    * calls from the new and old APIs, if this is necessary for
  526.    * maintaining old code.
  527.    * 
  528.    * The default state of the channel is buffered.
  529.    * @param buffered Whether to set the channel buffered or unbuffered.
  530.    */
  531.   void set_buffered(bool buffered);
  532.  
  533.   /** Get the buffering status of the I/O channel.
  534.    * @return The buffering status of the channel.
  535.    */
  536.   
  537.   /** Returns whether @a channel  is buffered.
  538.    * @return <tt>true</tt> if the @a channel  is buffered.
  539.    */
  540.   bool get_buffered() const;
  541.  
  542.   /** Returns an IOCondition depending on whether there is data to be
  543.    * read/space to write data in the internal buffers in the I/O channel.
  544.    * Only the flags Glib::IO_IN and Glib::IO_OUT may be set.
  545.    * @return Bitwise combination of Glib::IOCondition flags.
  546.    */
  547.   
  548.   /** This function returns a G::IOCondition depending on whether there
  549.    * is data to be read/space to write data in the
  550.    * internal buffers in the G::IOChannel. Only the flags G::IO_IN and
  551.    * G::IO_OUT may be set.
  552.    * @return A G::IOCondition.
  553.    */
  554.   IOCondition get_buffer_condition() const;
  555.  
  556.   /** Returns whether the file/socket/whatever associated with the I/O channel
  557.    * will be closed when the channel receives its final unref and is destroyed.
  558.    * The default value of this is <tt>true</tt> for channels created by
  559.    * create_from_file(), and <tt>false</tt> for all other channels.
  560.    * @return Whether the channel will be closed on the final unref of the
  561.    * IOChannel object.
  562.    */
  563.   
  564.   /** Returns whether the file/socket/whatever associated with @a channel 
  565.    * will be closed when @a channel  receives its final unref and is
  566.    * destroyed. The default value of this is <tt>true</tt> for channels created
  567.    * by g_io_channel_new_file(), and <tt>false</tt> for all other channels.
  568.    * @return Whether the channel will be closed on the final unref of
  569.    * the GIOChannel data structure.
  570.    */
  571.   bool get_close_on_unref() const;
  572.  
  573.   /** Setting this flag to <tt>true</tt> for a channel you have already closed
  574.    * can cause problems.
  575.    * @param do_close Whether to close the channel on the final unref of the
  576.    * IOChannel object.  The default value of this is <tt>true</tt> for channels
  577.    * created by create_from_file(), and <tt>false</tt> for all other channels.
  578.    */
  579.   
  580.   /** Setting this flag to <tt>true</tt> for a channel you have already closed
  581.    * can cause problems.
  582.    * @param do_close Whether to close the channel on the final unref of
  583.    * the GIOChannel data structure. The default value of
  584.    * this is <tt>true</tt> for channels created by g_io_channel_new_file(),
  585.    * and <tt>false</tt> for all other channels.
  586.    */
  587.   void set_close_on_unref(bool do_close);
  588.  
  589.   /** Sets the encoding for the input/output of the channel.
  590.    * The internal encoding is always UTF-8.  The default encoding for the
  591.    * external file is UTF-8.  The encoding <tt>""</tt> is safe to use with
  592.    * binary data.
  593.    *
  594.    * The encoding can only be set if one of the following conditions
  595.    * is true:
  596.    *
  597.    * -# The channel was just created, and has not been written to or read from
  598.    *  yet.
  599.    * -# The channel is write-only.
  600.    * -# The channel is a file, and the file pointer was just repositioned by a
  601.    *  call to seek_position().  (This flushes all the internal buffers.)
  602.    * -# The current encoding is <tt>""</tt> or UTF-8.
  603.    * -# One of the read methods has just returned Glib::IO_STATUS_EOF (or, in
  604.    *  the case of read_to_end(), Glib::IO_STATUS_NORMAL).
  605.    * -# The read() method has returned Glib::IO_STATUS_AGAIN or thrown
  606.    *  a Glib::Error exception.  This may be useful in the case of
  607.    *  ConvertError::ILLEGAL_SEQUENCE.  Returning one of these statuses
  608.    *  from read_line() or read_to_end() does <em>not</em> guarantee that
  609.    *  the encoding can be changed.
  610.    *
  611.    * Channels which do not meet one of the above conditions cannot call
  612.    * seek_position() with a seek type of Glib::SEEK_TYPE_CUR and, if they
  613.    * are "seekable", cannot call write() after calling one of the API
  614.    * "read" methods.
  615.    *
  616.    * @param encoding The encoding name, or <tt>""</tt> for binary.
  617.    * @return Glib::IO_STATUS_NORMAL if the encoding was successfully set.
  618.    * @throw Glib::IOChannelError
  619.    */
  620.   IOStatus set_encoding(const std::string& encoding = std::string());
  621.   
  622.  
  623.   /** Get the encoding of the I/O channel.
  624.    * @return The current encoding of the channel.
  625.    */
  626.   std::string get_encoding() const;
  627.   
  628.  
  629.   void set_line_term(const std::string& term = std::string());
  630.   
  631.  
  632.   std::string get_line_term() const;
  633.   
  634.  
  635.   /** Creates an IOSource object.
  636.    * Create a slot from a function to be called when condition is met
  637.    * for the channel with sigc::ptr_fun() or sigc::mem_fun() and pass
  638.    * it into the connect() function of the returned IOSource object.
  639.    * Polling of the channel will start when you attach a MainContext
  640.    * object to the returned IOSource object using its attach() function.
  641.    *
  642.    * Glib::signal_io().connect() is a simpler interface to the same
  643.    * functionality, for the case where you want to add the source to the
  644.    * default main context.
  645.    * @param condition The condition to watch for.
  646.    * @return An IOSource object that can be polled from a MainContext's event loop.
  647.    */
  648.   Glib::RefPtr<IOSource> create_watch(IOCondition condition);
  649.   
  650.  
  651.   virtual void reference()   const;
  652.   virtual void unreference() const;
  653.   
  654.  
  655.   GIOChannel*       gobj()       { return gobject_; }
  656.   const GIOChannel* gobj() const { return gobject_; }
  657.  
  658. protected:
  659.   GIOChannel* gobject_;
  660.  
  661.   /** Constructor that should be used by derived classes.
  662.    * Use this constructor if you want to inherit from IOChannel.
  663.    * It will set up a GIOChannel that will call the vfuncs of your 
  664.    * class even if it is being used from C code, and it will keep
  665.    * a reference to the C++ code while the GIOChannel exists.
  666.    */
  667.   IOChannel();
  668.   
  669.  
  670. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  671.   IOChannel(GIOChannel* gobject, bool take_copy);
  672. #endif
  673.  
  674.   virtual IOStatus read_vfunc(char* buf, gsize count, gsize& bytes_read);
  675.   virtual IOStatus write_vfunc(const char* buf, gsize count, gsize& bytes_written);
  676.   virtual IOStatus seek_vfunc(gint64 offset, SeekType type);
  677.   virtual IOStatus close_vfunc();
  678.   virtual IOStatus set_flags_vfunc(IOFlags flags);
  679.   virtual IOFlags  get_flags_vfunc();
  680.   virtual Glib::RefPtr<Glib::Source> create_watch_vfunc(IOCondition cond);
  681.  
  682. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  683.   friend class Glib::GlibmmIOChannel;
  684. #endif
  685.  
  686.  
  687. };
  688.  
  689. Glib::RefPtr<IOChannel> wrap(GIOChannel* gobject, bool take_copy = false);
  690.  
  691. } // namespace Glib
  692.  
  693.  
  694. #endif /* _GLIBMM_IOCHANNEL_H */
  695.  
  696.